home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / DoOneEvent.3 < prev    next >
Text File  |  1994-09-20  |  6KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tk_DoOneEvent(3)      Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_DoOneEvent, Tk_MainLoop, Tk_HandleEvent - wait for events
  12.      and invoke event handlers
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      int
  18.      Tk_DoOneEvent(_f_l_a_g_s)                                          |
  19.  
  20.      Tk_MainLoop()
  21.  
  22.      Tk_HandleEvent(_e_v_e_n_t_P_t_r)
  23.  
  24. ARGUMENTS
  25.      int      _f_l_a_g_s       (in)      This  parameter  is  normally  |
  26.                                     zero.   It  may  be  an OR-ed  |
  27.                                     combination  of  any  of  the  |
  28.                                     following      flag     bits:  |
  29.                                     TK_X_EVENTS,  TK_FILE_EVENTS,  |
  30.                                     TK_TIMER_EVENTS,  |
  31.                                     TK_IDLE_EVENTS,  |
  32.                                     TK_ALL_EVENTS,             or  |
  33.                                     TK_DONT_WAIT.
  34.  
  35.      XEvent   *_e_v_e_n_t_P_t_r   (in)      Pointer   to   X   event   to
  36.                                     dispatch      to     relevant
  37.                                     handler(s).
  38. _________________________________________________________________
  39.  
  40.  
  41. DESCRIPTION
  42.      These three  procedures  are  responsible  for  waiting  for
  43.      events  and  dispatching  to event handlers created with the
  44.      procedures   Tk_CreateEventHandler,    Tk_CreateFileHandler,
  45.      Tk_CreateTimerHandler,  and Tk_DoWhenIdle.  Tk_DoOneEvent is
  46.      the key procedure.  It waits for a single event of any  sort
  47.      to  occur,  invokes  the handler(s) for that event, and then
  48.      returns.  Tk_DoOneEvent first checks for X events and  file-
  49.      related   events;   if  one  is  found  then  it  calls  the
  50.      handler(s) for the event and returns.  If there are no X  or
  51.      file  events  pending,  then  Tk_DoOneEvent checks to see if
  52.      timer callbacks are ready;  if so, it makes a  single  call-
  53.      back   and  returns.   If  no  timer  callbacks  are  ready,
  54.      Tk_DoOneEvent checks for Tk_DoWhenIdle  callbacks;   if  any
  55.      are  found, it invokes all of them and returns.  Finally, if
  56.      events or work have been found found,  Tk_DoOneEvent  sleeps
  57.      until  a  timer, file, or X event occurs;  then it processes
  58.      the first  event  found  (in  the  order  given  above)  and
  59.      returns.   The normal return value is 1 to signify that some
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_DoOneEvent(3)      Tk Library Procedures
  71.  
  72.  
  73.  
  74.      event or callback was processed.
  75.  
  76.      If the _f_l_a_g_s argument to Tk_DoOneEvent is non-zero  then  it  |
  77.      restricts  the  kinds  of  events  that will be processed by  |
  78.      Tk_DoOneEvent.  _F_l_a_g_s may be an OR-ed combination of any  of  |
  79.      the following bits:                                           |
  80.  
  81.      TK_X_EVENTS -                                                      ||
  82.                              Process X events.                     |
  83.  
  84.      TK_FILE_EVENTS -                                                   ||
  85.                              Process file events.                  |
  86.  
  87.      TK_TIMER_EVENTS -                                                  ||
  88.                              Process timer events.                 |
  89.  
  90.      TK_IDLE_EVENTS -                                                   ||
  91.                              Process Tk_DoWhenIdle callbacks.      |
  92.  
  93.      TK_ALL_EVENTS -                                                    ||
  94.                              Process   all   kinds   of   events:  |
  95.                              equivalent to OR-ing together all of  |
  96.                              the  above  flags or specifying none  |
  97.                              of them.                              |
  98.  
  99.      TK_DONT_WAIT -                                                     ||
  100.                              Don't  sleep:   process  only events  |
  101.                              that are ready at the  time  of  the  |
  102.                              call.                                 |
  103.  
  104.      If   any   of   the   flags   TK_X_EVENTS,   TK_FILE_EVENTS,  |
  105.      TK_TIMER_EVENTS,  or  TK_IDLE_EVENTS  is  set, then the only  |
  106.      events that will be considered are those for which flags are  |
  107.      set.  Setting none of these flags is equivalent to the value  |
  108.      TK_ALL_EVENTS, which causes all event types to be processed.  |
  109.  
  110.      The TK_DONT_WAIT flag causes Tk_DoWhenIdle not  to  put  the  |
  111.      process  to sleep:  it will check for events but if none are  |
  112.      found then it returns immediately with a return value  of  0  |
  113.      to  indicate that no work was done.  Tk_DoOneEvent will also  |
  114.      return 0 without doing anything if _f_l_a_g_s  is  TK_IDLE_EVENTS  |
  115.      and there are no Tk_DoWhenIdle callbacks pending.
  116.  
  117.      Tk_MainLoop is a procedure  that  loops  repeatedly  calling
  118.      Tk_DoOneEvent.   It  returns only when there are no applica-
  119.      tions left in this  process  (i.e.  no  main  windows  exist
  120.      anymore).   Most  X applications will call Tk_MainLoop after
  121.      initialization;  the main execution of the application  will
  122.      consist entirely of callbacks invoked by Tk_DoOneEvent.
  123.  
  124.      Tk_HandleEvent  is  a  lower-level  procedure   invoked   by
  125.      Tk_DoOneEvent.   It  makes  callbacks  to any event handlers
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tk_DoOneEvent(3)      Tk Library Procedures
  137.  
  138.  
  139.  
  140.      (created  by  calls  to  Tk_CreateEventHandler)  that  match
  141.      _e_v_e_n_t_P_t_r  and  then returns.  In some cases it may be useful
  142.      for an application  to  read  events  directly  from  X  and
  143.      dispatch  them  by  calling  Tk_HandleEvent,  without  going
  144.      through the additional mechanism provided by Tk_DoOneEvent.
  145.  
  146.      These procedures may be invoked recursively.   For  example,
  147.      it  is  possible  to invoke Tk_DoOneEvent recursively from a
  148.      handler called by Tk_DoOneEvent.  This sort of operation  is
  149.      useful in some modal situations, such as when a notifier has
  150.      been popped up and an application wishes  to  wait  for  the
  151.      user to click a button in the notifier before doing anything
  152.      else.
  153.  
  154.  
  155. KEYWORDS
  156.      callback, event, handler, idle, timer
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.